package com.vividstores.integration.mq;

import java.io.IOException;

import com.ibm.mq.MQException;

public interface MQFileReceiver extends MQFileDispatcher {

	/**
	 * <p>
	 * 从Queue中读取批量文件信息，包括文件头和文件体，以及附加的业务字段数据。 Queue的连接信息通过
	 * {@link MQFileDispatcher}指定。
	 * </p>
	 * <p>
	 * 调用方法时，若Queue中没有文件传输请求，则一直等待在Queue上，线程将会挂起，直到有文件传输请求到达。
	 * </p>
	 * <p>
	 * 文件传输请求到达时，文件的头信息和文件体均已到达Queue中，方法会读取并使用{@link MQFileReceiverHandler}
	 * 计算本地文件存储路径并将从Queue中读取到的文件存放于计算结果指定的文件路径中。
	 * </p>
	 * <p>
	 * 方法结束时返回{@link MQFileBundle}，包含了发送方指定的文件头信息和业务字段数据，同时在
	 * {@link MQFileBundle#getFiles()}的{@link MQFile#getFile()}中会含有指向本地存储的文件信息。
	 * </p>
	 * <p>
	 * 方法正常结束时会向MQ提交事务，完整的文件请求信息会从队列中读出并删除。若方法抛出异常非正常结束时，会向MQ回滚事务，文件请求信息会驻留在队列中。
	 * 应用程序需要记录日志并检查Queue中请求信息。
	 * </p>
	 * 
	 * @param handler
	 *            用于处理计算{@link MQFile#getFile()}文件输出路径
	 * @return 从Queue中读出并解析后的批量文件数据，输出文件根据{@link MQFileReceiverHandler}计算出输出路径，
	 *         {@link MQFileBundle#getFiles()}中含有本地存储的文件位置信息
	 * @throws IOException
	 *             从Queue中读取文件和向本地写入文件过程中可能抛出异常
	 * @throws MQException
	 *             当WebSphere MQ产生错误时抛出
	 */
	public MQFileBundle receive(MQFileReceiverHandler handler)
			throws IOException, MQException;

}
